---
title: 라우팅 참조
i18nReady: true
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';

Astro에는 별도의 라우팅 설정이 없습니다.

특별한 `src/pages/` 디렉터리에 위치한 모든 [지원되는 페이지 파일](/ko/basics/astro-pages/#지원되는-페이지-파일)이 라우트를 생성합니다. 파일 이름에 [매개변수](#params)가 포함되어 있을 경우 라우트는 동적으로 여러 페이지를 생성할 수 있으며, 그렇지 않으면 단일 페이지를 생성합니다.

기본적으로 모든 Astro 페이지 라우트와 엔드포인트는 빌드 타임에 생성되어 사전 렌더링됩니다. [요청 시 서버 렌더링](/ko/guides/on-demand-rendering/)은 개별 라우트에 대해 설정하거나 기본값으로 설정할 수 있습니다.

## `prerender`

<p>

**타입:** `boolean`<br />
**기본값:** 정적 모드에서 `true`(기본값); `output: 'server'` 구성 시 `false`<br />
<Since v="1.0.0" />
</p>

각 개별 라우트에서 내보내는 값으로, 사전 렌더링 여부를 결정합니다.

기본적으로 모든 페이지와 엔드포인트는 사전 렌더링되며 빌드 타임에 정적으로 생성됩니다. 하나 이상의 라우트에서 사전 렌더링을 선택 해제할 수 있으며, 동일한 프로젝트에서 정적 렌더링 및 요청 시 렌더링 라우트를 모두 가질 수 있습니다.

### 페이지별 재정의 

개별 라우트에 대해 [요청 시 렌더링](/ko/guides/on-demand-rendering/)을 활성화하려면 해당 파일에서 `prerender` 값을 `false`로 내보내어 기본값을 재정의할 수 있습니다:

```astro title="src/pages/rendered-on-demand.astro" {2}
---
export const prerender = false
---
<!-- 서버 렌더링된 콘텐츠 -->
<!-- 사이트의 나머지 부분은 정적 -->
```

### `server` 모드로 전환

모든 라우트의 기본값을 재정의하려면 [`output: 'server'`](/ko/reference/configuration-reference/#output)를 설정하면 됩니다. 이 출력 모드에서는 모든 페이지와 엔드포인트가 사전 렌더링되는 대신 기본적으로 요청 시 서버에서 생성됩니다.

`server` 모드에서 개별 라우트에 대한 사전 렌더링을 활성화하려면 해당 파일에서 `prerender` 값을 `true`로 내보내면 됩니다:

```astro title="src/pages/static-about-page.astro" {3}
---
// `output: 'server'` 구성 시
export const prerender = true
---
<!-- 정적인 소개 페이지 -->
<!-- 다른 모든 페이지는 요청 시 렌더링 -->
```

## `partial`

<p>

**타입:** `boolean` <br />
**기본값:** `false` <br />
<Since v="3.4.0" />
</p>

개별 라우트에서 내보내는 값으로, 전체 HTML 페이지로 렌더링할지 여부를 결정합니다.

기본적으로 예약된 `src/pages/` 디렉터리에 위치한 모든 파일은 자동으로 `<!DOCTYPE html>` 선언과 Astro의 스코프가 지정된 스타일 및 스크립트와 같은 추가적인 `<head>` 콘텐츠를 포함합니다.

개별 라우트에 대해 콘텐츠를 [페이지 부분](/ko/basics/astro-pages/#페이지-부분-page-partials)으로 지정하려면 해당 파일에서 `partial`에 대한 값을 내보내어 기본값을 재정의할 수 있습니다:

```astro title="src/pages/my-page-partial.astro" {2}
---
export const partial = true
---
<!-- URL에서 사용할 수 있는 생성된 HTML -->
<!-- 렌더링 라이브러리에서 사용 가능 -->
```

`export const partial`은 정적으로 식별 가능해야 합니다. 다음과 같은 값을 가질 수 있습니다:

- 불리언 값인 __`true`__.
- `import.meta.env.USE_PARTIALS`와 같은 import.meta.env를 사용하는 환경 변수

## `getStaticPaths()`

<p>
**타입:** `(options: GetStaticPathsOptions) => Promise<GetStaticPathsResult> | GetStaticPathsResult` <br />
<Since v="1.0.0" />
</p>

파일 경로에 하나 이상의 [매개변수](#params)가 있는 단일 `.astro` 페이지 컴포넌트에서 여러 개의 사전 렌더링된 페이지 라우트를 생성하는 함수입니다. 이는 정적 사이트 빌딩이라고도 하는, 빌드 타임에 생성될 라우트에 사용됩니다.

`getStaticPaths()` 함수는 Astro가 사전 렌더링할 URL 경로를 결정하기 위한 객체 배열을 반환해야 합니다. 각 객체는 라우트 경로를 지정하는 `params` 객체를 포함해야 합니다. 선택적으로 각 페이지 템플릿에 [전달할 데이터](#props를-사용한-데이터-전달)가 있는 `props` 객체를 포함할 수 있습니다.

```astro title="src/pages/blog/[post].astro" "post"
---
// `server` 모드에서 사전 렌더링 선택:
// export const prerender = true

export async function getStaticPaths() {
  return [
    // { params: { /* required */ }, props: { /* 선택적 */ } },
    { params: { post: '1' } }, // [post]는 매개변수입니다.
    { params: { post: '2' } }, // 반드시 파일 이름과 일치해야 합니다.
    // ...
  ];
}
---
<!-- HTML 템플릿 -->
```

`getStaticPaths()`는 [동적 라우팅](/ko/guides/endpoints/#params-및-동적-라우팅)을 위한 정적 파일 엔드포인트에서도 사용될 수 있습니다.

:::tip
TypeScript를 사용할 때는 [`GetStaticPaths`](/ko/guides/typescript/#getstaticpaths-타입-추론) 타입 유틸리티를 사용하여 `params`와 `props`에 대한 타입 안전 접근을 보장할 수 있습니다.
:::

:::caution
`getStaticPaths()` 함수는 페이지가 로드되기 전에 자체적으로 격리된 스코프에서 한 번 실행됩니다. 따라서 파일 가져오기를 제외하고는 부모 스코프의 어떤 것도 참조할 수 없습니다. 이 요구사항을 위반하면 컴파일러가 경고를 표시합니다.
:::

### `params`

`getStaticPaths()`가 반환하는 배열의 각 객체에 있는 `params` 키는 Astro에게 어떤 라우트를 빌드할지 알려줍니다.

`params`의 키는 컴포넌트 파일 경로에 정의된 매개변수와 일치해야 합니다. 각 `params` 객체의 값은 페이지 이름에 사용된 매개변수와 일치해야 합니다. `params`는 URL로 인코딩되므로 문자열 값만 지원됩니다.

예를 들어, `src/pages/posts/[id].astro`는 파일 이름에 `id` 매개변수를 가지고 있습니다. 다음은 `.astro` 컴포넌트의 `getStaticPaths()` 함수가 빌드 시점에 Astro에게 `posts/1`, `posts/2`, `posts/3`을 정적으로 생성하도록 지시합니다.

```astro title="src/pages/posts/[id].astro"
---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>
```

### `props`를 사용한 데이터 전달

생성된 각 페이지에 추가 데이터를 전달하려면 `getStaticPaths()`가 반환하는 배열의 각 객체에 `props` 값을 설정할 수 있습니다. `params`와 달리 `props`는 URL로 인코딩되지 않으므로 문자열로만 제한되지 않습니다.

예를 들어, 원격 API에서 가져온 데이터로 페이지를 생성하는 경우 `getStaticPaths()`에서 전체 데이터 객체를 페이지 컴포넌트에 전달할 수 있습니다. 페이지 템플릿은 `Astro.props`를 사용하여 각 게시물의 데이터를 참조할 수 있습니다.

```astro title="src/pages/posts/[id].astro" {9}
---
export async function getStaticPaths() {
  const response = await fetch('...');
  const data = await response.json();

  return data.map((post) => {
    return {
      params: { id: post.id },
      props: { post },
    };
  });
}

const { id } = Astro.params;
const { post } = Astro.props;
---
<h1>{id}: {post.name}</h1>
```

### `routePattern`

<p>

**타입:** `string` <br />
<Since v="5.14.0" />
</p>

[`getStaticPaths()`](#getstaticpaths) 옵션에서 사용할 수 있는 속성으로, 현재 [`routePattern`](/ko/reference/api-reference/#routepattern)을 문자열로 접근합니다.

이는 일반적으로 `getStaticPaths()` 범위에서는 접근할 수 없는 [Astro 렌더링 컨텍스트](/ko/reference/api-reference/)의 데이터를 제공하며, 각 페이지 라우트에 대한 `params`와 `props`를 계산하는 데 유용할 수 있습니다.

`routePattern`은 항상 파일 경로의 원본 동적 세그먼트 정의(예: `/[...locale]/[files]/[slug]`)를 반영합니다. 반면 `params`는 페이지에 대한 명시적 값(예: `/fr/fichiers/article-1/`)이 됩니다.

다음은 사용자 정의 `getLocalizedData()` 도우미 함수에 `routePattern`을 전달하여 라우트 세그먼트를 현지화하고 정적 경로 배열을 반환하는 방법을 보여주는 예시입니다. [params](/ko/reference/routing-reference/#params) 객체는 각 라우트 세그먼트(`locale`, `files`, `slug`)에 대한 명시적 값으로 설정됩니다. 이 값들은 라우트를 생성하는 데 사용되며 `Astro.params`를 통해 페이지 템플릿에서 활용할 수도 있습니다.

```astro title="src/pages/[...locale]/[files]/[slug].astro" "routePattern" "getLocalizedData"
---
import { getLocalizedData } from "../../../utils/i18n";

export async function getStaticPaths({ routePattern }) {
  const response = await fetch('...');
  const data = await response.json();

  console.log(routePattern); // [...locale]/[files]/[slug]

  // 사용자 정의 도우미 함수에 `routePattern`를 전달하여 호출하여 정적 경로를 생성합니다.
  return data.flatMap((file) => getLocalizedData(file, routePattern));
}

const { locale, files, slug } = Astro.params;
---
```

### `paginate()`

<p>

<Since v="1.0.0" />
</p>

[`getStaticPaths()`](#getstaticpaths)에서 반환할 수 있는 함수로, 콘텐츠 항목 모음을 개별 페이지로 나눕니다.

`paginate()`는 페이지네이션된 컬렉션의 각 페이지마다 하나의 URL을 생성하기 위해 `getStaticPaths()`에서 반환할 필요한 배열을 자동으로 생성합니다. 페이지 번호는 `param`으로 전달되고, 페이지 데이터는 `page` prop으로 전달됩니다.

다음 예시는 150개의 항목을 가져와 `paginate` 함수에 전달하고, 빌드 타임에 페이지당 10개의 항목을 표시할 정적으로 사전 렌더링된 페이지를 생성합니다:

```astro title="src/pages/pokemon/[page].astro"
---
export async function getStaticPaths({ paginate }) {
  // fetch(), getCollection() 등으로 데이터 로드
  const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`);
  const result = await response.json();
  const allPokemon = result.results;

  // 모든 항목에 대한 페이지가 매겨진 경로 컬렉션을 반환
  return paginate(allPokemon, { pageSize: 10 });
}

const { page } = Astro.props;
---
```

`paginate()`는 다음과 같은 인수를 가집니다:
- `data` - `paginate()` 함수에 전달된 페이지의 데이터를 포함하는 배열
- `options` - 다음 속성을 가진 선택적 객체:
  - `pageSize` - 페이지당 표시되는 항목 수(기본값 `10`)
  - `params` - 동적 라우트 생성을 위한 추가 매개변수 전달
  - `props` - 각 페이지에서 사용할 수 있는 추가 props 전달

`paginate()`는 `[page].astro` 또는 `[...page].astro`의 파일 이름을 가정합니다. `page` 매개변수는 URL에서 페이지 번호가 됩니다:

- `/posts/[page].astro`는 `/posts/1`, `/posts/2`, `/posts/3` 등의 URL을 생성합니다.
- `/posts/[...page].astro`는 `/posts`, `/posts/2`, `/posts/3` 등의 URL을 생성합니다.

#### 페이지네이션 `page` prop

<p>

**타입:** `Page<TData>`
</p>

페이지네이션은 페이지가 매겨진 컬렉션의 단일 데이터 페이지를 나타내는 모든 렌더링된 페이지에 `page` prop을 전달합니다. 여기에는 페이지네이션한 데이터(`page.data`)와 페이지의 메타데이터(`page.url`, `page.start`, `page.end`, `page.total` 등)가 포함됩니다. 이 메타데이터는 "다음 페이지" 버튼이나 "100개 중 1-10 표시" 메시지와 같은 요소에 유용합니다.

##### `page.data`

<p>

**타입:** `Array<TData>`
</p>

현재 페이지에 대해 `paginate()` 함수에서 반환된 데이터 배열

##### `page.start`

<p>

**타입:** `number`
</p>

현재 페이지의 첫 번째 항목의 인덱스로, `0`부터 시작합니다. (예: `pageSize: 25`인 경우, 1페이지에서는 `0`, 2페이지에서는 `25` 등)

##### `page.end`

<p>

**타입:** `number`
</p>

현재 페이지의 마지막 항목의 인덱스입니다.

##### `page.size`

<p>

**타입:** `number`<br />
**기본값:** `10`
</p>

페이지당 총 항목 수입니다.

##### `page.total`

<p>

**타입:** `number`
</p>

모든 페이지의 총 항목 수입니다.

##### `page.currentPage`

<p>

**타입:** `number`
</p>

`1`부터 시작하는 현재 페이지 번호입니다.

##### `page.lastPage`

<p>

**타입:** `number`
</p>

총 페이지 수입니다.

##### `page.url.current`

<p>

**타입:** `string`
</p>

현재 페이지의 URL을 가져옵니다(canonical URL에 유용). [`base`](/ko/reference/configuration-reference/#base)에 대한 값이 설정된 경우, URL은 해당 값으로 시작합니다.

##### `page.url.prev`

<p>

**타입:** `string | undefined`
</p>

이전 페이지의 URL을 가져옵니다(1 페이지인 경우 `undefined`). [`base`](/ko/reference/configuration-reference/#base)에 대한 값이 설정된 경우, URL에 기본 경로가 추가됩니다.

##### `page.url.next`

<p>

**타입:** `string | undefined`
</p>

다음 페이지의 URL을 가져옵니다(더 이상 페이지가 없는경우 `undefined`). [`base`](/ko/reference/configuration-reference/#base)에 대한 값이 설정된 경우, URL에 기본 경로가 추가됩니다.

##### `page.url.first`

<p>

**타입:** `string | undefined`<br />
<Since v="4.12.0" />
</p>

첫 페이지의 URL을 가져옵니다(1페이지인 경우 `undefined`). [`base`](/ko/reference/configuration-reference/#base)에 대한 값이 설정된 경우, 기본 경로가 URL 앞에 추가됩니다.

##### `page.url.last`

<p>

**타입:** `string | undefined`<br />
<Since v="4.12.0" />
</p>

마지막 페이지의 URL을 가져옵니다(더 이상 페이지가 없는 경우 `undefined`). [`base`](/ko/reference/configuration-reference/#base)에 대한 값이 설정된 경우, 기본 경로가 URL 앞에 추가됩니다.
